# SOC Intelligence Base Module
# 情报查询基础模块 - 提供通用函数和基础类

import os
import asyncio
from typing import Optional, Dict, Any
from asyncio import Queue
from dotenv import load_dotenv, find_dotenv

# --- 环境变量加载 ---
dotenv_path = find_dotenv()
if dotenv_path:
    load_dotenv(dotenv_path)
else:
    print("警告: 未找到 .env 文件。请确保它位于项目根目录中，并包含API密钥。")

async def send_status(status_queue: Optional[Queue], step_name: str, message_type: str, data: dict):
    """
    辅助函数：向状态队列发送消息。

    参数:
        status_queue (Optional[Queue]): 状态消息队列，如果为 None 则不发送。
        step_name (str): 当前执行的步骤名称。
        message_type (str): 消息类型（例如 "tool_start", "tool_end", "tool_error"）。
        data (dict): 包含消息内容的字典。
    """
    if status_queue:
        await status_queue.put({
            "type": message_type,
            "step": step_name,
            "data": data
        })

def create_standardized_result(source: str, data: Any = None, error: str = None, status: str = "success") -> Dict[str, Any]:
    """
    创建标准化的查询结果格式。
    
    参数:
        source (str): 数据源名称
        data (Any): 查询结果数据
        error (str): 错误信息（如果有）
        status (str): 查询状态 ("success" 或 "failed")
    
    返回:
        Dict[str, Any]: 标准化的结果字典
    """
    return {
        "source": source,
        "data": data,
        "error": error,
        "status": status
    }

class IntelligenceQueryError(Exception):
    """情报查询异常基类"""
    pass

class ExternalIntelError(IntelligenceQueryError):
    """外部威胁情报查询异常"""
    pass

class InternalIntelError(IntelligenceQueryError):
    """内部情报查询异常"""
    pass

class APIKeyMissingError(IntelligenceQueryError):
    """API密钥缺失异常"""
    pass

# 常用的威胁情报指标类型
INDICATOR_TYPES = {
    'IPV4': 'ipv4',
    'IPV6': 'ipv6', 
    'DOMAIN': 'domain',
    'URL': 'url',
    'FILE_HASH': 'file_hash',
    'EMAIL': 'email',
    'USER_AGENT': 'user_agent'
}

# SOC分析中常用的风险等级
RISK_LEVELS = {
    'CRITICAL': 'critical',
    'HIGH': 'high',
    'MEDIUM': 'medium',
    'LOW': 'low',
    'INFO': 'info',
    'UNKNOWN': 'unknown'
}

def normalize_indicator_type(indicator_type: str) -> str:
    """
    标准化威胁指标类型名称。
    
    参数:
        indicator_type (str): 原始指标类型
        
    返回:
        str: 标准化后的指标类型
    """
    return indicator_type.lower().strip()

def calculate_confidence_score(detections: int, total_engines: int) -> float:
    """
    基于检测引擎数量计算置信度分数。
    
    参数:
        detections (int): 检测到威胁的引擎数量
        total_engines (int): 总引擎数量
        
    返回:
        float: 置信度分数 (0-100)
    """
    if total_engines == 0:
        return 0.0
    return min(100.0, (detections / total_engines) * 100)
